PySwarm Interface Application (Main Page)
__TOC__Starting with PySwarm V0.5, you no longer need to edit the PySwarm Python script to generate your animation sequences. Instead, you now select and enter the rules and parameters through the "PySwarm Interface Application" (PIA), and PIA builds the PySwarm script for you. Once the script is built, you can directly import the resulting file into your Carrara scene. How PIA Works PIA uses a PySwarm Shell (a text file) along with the rules and parameters you have set to build the Python Script file. You then import that script into your Carrara scene. This results in creating your .CAR BOID animation sequence. Installing PIA To install the application, simply copy the following two files into the directory of your choice. The application does not need to be registered with WIndows to run. However, I do recommend you create a new directory to hold the application files, so they can be easily updated when new versions become available. There are only two files needed to create your PySwarm scripts. *PIA.exe - The application executable. *PySwarm Shell Vxx.txt - A shell or wrapper containing the PySwarm Python script / program, excluding the parameter settings. Once you have copied these two files to your directory, you can drag and drop the PIA.exe icon to your desktop and/or your taskbar, and launch the application from there. Note that once you have run the application the first time, two new files will appear in the application's directory. *Script.pys - Contains the string that points to the current PySwarm shell needed to generate your PySwarm scripts. *Projects.pys - Contains the parameter settings for your PySwarm projects. You should not edit or delete these files, as they contain important settings and information PIA uses related to your projects, and how to generate PySwarm scripts. However, if for any reason they are deleted or corrupted, PIA will recreate them. Running PIA To run the PIA application, you can: *Use WIndows Explorer to navigate to the folder containing PIA.exe, and clicking (or double-clicking) on the icon. *Drag and drop the PIA.exe icon to your desktop and/or your taskbar, and launch the application from there. Getting Started with PIA When you first run PIA, the following screen will appear: Selecting the Script Shell The first thing you will want to do is to tell PIA where to find the "PySwarm Source Script Shell." This text file contains the shell (or wrapper) Python script text PIA will need to generate the PySwarm script. The reason the PySwarm script is generated this way is to simplify updating the shell file ("PySwarm Shell Vxx.txt") without having to update the application. To set this field, click the "Browse..." button next to the Script Shell field. This will cause the "Open" dialog window to appear. If you followed the installation instructions above, the file named "PySwarm Shell Vxx.txt" should appear in the list. If not, you will need to navigate to the folder containing the shell file. Select the file and click the "Open" button. The PySwarm Source Script Shell field should now contain the directory sequence and file name needed to generate PySwarm scripts. Once this field has been set to point to the shell text file, you won't need to update this again until a new version of the shell file is released. Managing PySwarm Projects PIA allows you to maintain up to nine (9) different projects at a time. You can think of a project in relation to different Carrara scenes. That is, generally you will have one project for each Carrara animation scene you are working on. Each project contains its own complete set of parameter settings. That way, you can easily switch between projects without loosing your work on another. The Default Settings The first project in the project list is always called "Default." You will not be able to generate PySwarm scripts from this entry. However, this parameter set is useful for two reasons. First, when you add new projects, they are always initialized to the default settings. And second, you can quickly and easily reset a project's parameters back to the default settings. As such, you can change any of the settings to your personal preferences at any time. For example, suppose you always name the Carrara camera object you manipulate with PySwarm "PySwarm Camera." By entering that string into the Camera Name field for the Default project, that name will automatically be entered when you create a new project. Adding a New Project To add a project to the PySwarm project list, click the "New" button next to the project drop-down menu. When the "New Project" dialog window appears, enter an unique name for the project and click "Ok." PIA will create a new project entry and initialize all of the parameter settings to their default values. It is recommended you choose project names that closely match the names of the Carrara scene files' names. Also, note that PIA will allow you to enter multiple projects with the same name if you so desire. Selecting a Project to Work With To select a project, click the down arrow to the right of the project drop-down menu, the select the project. PIA will automatically load the parameter settings last saved for that project into the form fields. Saving the Parameter Settings At any time while working with PIA, you can force a save of the entire set of projects' parameter settings to the "Projects.pys" file by clicking the "Save Project Parameters to File" button. While PIA will automatically save all the settings before generating a script or exiting the program, this button is useful in case of a system error (e.g., "Blue screen of death") or power failure. Resetting Project Settings Back to Default There might be occasions when it is easier and/or faster to reset your currently selected project parameters back to the default settings than to edit them. You can do this by clicking the "Reset Parameters to Default" button, and then confirm the reset by clicking "OK" in the Confirmation dialog window. Only the currently selected project's parameters are reset. Deleting a Project While being able to work with up to 9 projects at a time may seem like a lot, there may be times when you need to do some clean-up. Once you have completed a Carrara project and you no longer need the project entry, you can reclaim the entry in the project list by selecting the project and clicking the "Delete" button. Then confirm the delete action by clicking "OK" in the Confirmation dialog window. Working With the Parameters PIA provides the ability to manipulate and modify all of the PySwarm parameters available to create BOID animation sequences. To begin modifying the parameters, make sure you have selected the right project you want to work with (as described above). The currently selected project name always appears in drop-down menu under "PySwarm Projects" at the bottom of the PIA window. Context Help If you are not sure what what a parameter is for, start by sliding your mouse cursor over the field. A short context-sensitive help will pop up providing a brief description. If more details are needed, refer to this Wiki section for further details. Parameter Organization All of the PIA parameters are organized into tabs as described below. Click on the hyperlink to bring up more details about the parameters. *Scene parameters - General parameters related to the Carrara scene *BOIDs parameters - Those related to initial BOID settings and motion operations *Rules parameters - The remaining tabs are related to each of the eight PySwarm rules **Cohesion - BOIDs attempt to group together by moving towards the group’s center of mass (the average of all BOIDs’ positions). **Separation - BOIDs attempt to keep some predefined safe distance between themselves and all other BOIDs. You can think of this like BOIDs attempting to keep some personal space. This works to counteract too much COHESION. **Alignment - BOIDs attempt to match their velocity (speed and heading) with the others in the group. **Containment - BOIDs attempt to stay inside (safe) or outside (restricted) specified regions of space. When BOIDs venture outside safe regions or inside restricted regions, they will naturally try to alter their course to go back inside the closest safe region. **Attraction - BOIDs attempt to move towards a specified object in the Carrara scene. Like “moths to a flame,” use an attractor to draw BOIDs towards a specific location in your scene. Also, when attractor objects move around in the scene, the BOIDs will attempt to follow. So you can use an attractor to draw BOIDs along a specified path or route. **Landing - BOIDs land on the ground if they fly to (strike) it. When BOIDs land, they will remain there for some random period of time, as determined by the rule's parameters. **Speed Limit - BOIDs cannot go less than or exceed a specified speed range. **Max Turn - BOIDs are limited in the turning angle that they can make. For example, planes and cars cannot turn completely around instantaneously. Note that when a rule is activated, that rule's tab is highlighted. This makes it easy to see which rules are currently active for your project. Generating the PySwarm Script Quitting PIA To exit the program, click the "Exit" button. PIA will automatically save the project parameter settings to the "Projects.pys" file before closing.